@magne4000 is it possible to access the flag of the current feature the processed $README.md.ts is related too. I would like to have a default wrapper which is based on the flag and category of the feature package. props.meta provide the full list of flags, a posibility to test but no information about the current feature.

@magne4000 is it possible to access the flag of the current feature the processed $README.md.ts is related too. I would like to have a default wrapper which is based on the flag and category of the feature package. props.meta provide the full list of flags, a posibility to test but no information about the current feature.

The "current feature" is not necessarily defined by a flag, or could be behind multiple flag, so not possible. And currently we have no way to know if a file will be replaced by another later in the process.

I really like it!
Once this PR is merged, I think that generating a Table of Content could be a good idea.

@magne4000 is it possible to access the flag of the current feature the processed $README.md.ts is related too. I would like to have a default wrapper which is based on the flag and category of the feature package. props.meta provide the full list of flags, a posibility to test but no information about the current feature.

The "current feature" is not necessarily defined by a flag, or could be behind multiple flag, so not possible. And currently we have no way to know if a file will be replaced by another later in the process.

It is less about the "current feature" more about the context a file is processed.
If the $README.md.ts is in the folder boilerplates/react/files, the values for flag="react" and based on a lookup in features.ts the category="Frontend Framework". I was hoping this information is already somewhere available as I did not wanted to look at the file path or parse the package.json. This would allow to make the main use case of adding content even more simple.

I really like it! Once this PR is merged, I think that generating a Table of Content could be a good idea.

I have thought about this, it's not really hard but my Markdown Viewer in VS Code provides this out of the box.

Open Question:

• should I replace/remove the old readme parser and upgrade all READMEs
• is the feature to create markdown elements of the old library needed? - except for creating the link in boilerplates/shared/files/$README.md.ts I coudn't finde any usage.

It is less about the "current feature" more about the context a file is processed. If the $README.md.ts is in the folder boilerplates/react/files, the values for flag="react" and based on a lookup in features.ts the category="Frontend Framework". I was hoping this information is already somewhere available as I did not wanted to look at the file path or parse the package.json. This would allow to make the main use case of adding content even more simple.

I have an alternative proposal. Why not explicitly give the flag as a parameter to the loader or to the finalize function? in boilerplates/react/files, we indeed know we are in react, so we can give "react" as an argument (I'm not a fan of implicit behaviors in this part of the code anyway).

should I replace/remove the old readme parser and upgrade all READMEs

Replace the old one yes 👍

is the feature to create markdown elements of the old library needed? - except for creating the link in boilerplates/shared/files/$README.md.ts I coudn't finde any usage.

You can remove everything I think. Creating markdown tags manually is probably better anyway for IDEs that support embedded syntax highlighting.

It is less about the "current feature" more about the context a file is processed. If the $README.md.ts is in the folder boilerplates/react/files, the values for flag="react" and based on a lookup in features.ts the category="Frontend Framework". I was hoping this information is already somewhere available as I did not wanted to look at the file path or parse the package.json. This would allow to make the main use case of adding content even more simple.

I have an alternative proposal. Why not explicitly give the flag as a parameter to the loader or to the finalize function? in boilerplates/react/files, we indeed know we are in react, so we can give "react" as an argument (I'm not a fan of implicit behaviors in this part of the code anyway).

Thats what I would do if the value of flag is part of props.meta.flag:

I would access the flag during loadMarkdown or it could be provide with the content.finalize()call.

export default async function getReadme(props: TransformerProps) {
  const content = await loadMarkdown(props);
  const flags = Array.from(props.meta.BATI)
    .filter((f) => (f as string) !== "force")
    .map((f) => `--${f}`)
    .join(" ");
  const v = getVersion();

  //language=Markdown
  const intro = `#  Markdown`;

  content.addMarkdown(intro);

  return content.finalize(props);
}

should I replace/remove the old readme parser and upgrade all READMEs

Replace the old one yes 👍

is the feature to create markdown elements of the old library needed? - except for creating the link in boilerplates/shared/files/$README.md.ts I coudn't finde any usage.

You can remove everything I think. Creating markdown tags manually is probably better anyway for IDEs that support embedded syntax highlighting.

Why not make it even simpler for the main use case, which is adding markdown without any conditions, as simple as possible by having a specific naming e.g. boilerplate/react/README.inc.md and then include the files in the the section "Frontend framework" with flag="react". This would allow full markdown syntax support.

Thats what I would do if the value of flag is part of props.meta.flag:

I would access the flag during loadMarkdown or it could be provide with the content.finalize()call.

export default async function getReadme(props: TransformerProps) {
  const content = await loadMarkdown(props);
  const flags = Array.from(props.meta.BATI)
    .filter((f) => (f as string) !== "force")
    .map((f) => `--${f}`)
    .join(" ");
  const v = getVersion();

  //language=Markdown
  const intro = `#  Markdown`;

  content.addMarkdown(intro);

  return content.finalize(props);
}

Sorry I'm still not sure to understand. In this example, where is this file located? Then, let's assume that we have access to this flag under props.meta.flag, how would you use it?

Thats what I would do if the value of flag is part of props.meta.flag:
I would access the flag during loadMarkdown or it could be provide with the content.finalize()call.

export default async function getReadme(props: TransformerProps) {
  const content = await loadMarkdown(props);
  const flags = Array.from(props.meta.BATI)
    .filter((f) => (f as string) !== "force")
    .map((f) => `--${f}`)
    .join(" ");
  const v = getVersion();

  //language=Markdown
  const intro = `#  Markdown`;

  content.addMarkdown(intro);

  return content.finalize(props);
}

Sorry I'm still not sure to understand. In this example, where is this file located? Then, let's assume that we have access to this flag under props.meta.flag, how would you use it?

The code above is a boilerplate/react/files/$README.md.ts file, which is a file as part of the feature flag react. If theoretical props.meta.flag would provide react, I would add this as a second parameter to the function parseMarkdown which creates the instance of the markdown class.
packages/core/src/loaders.ts:

export async function loadMarkdown({ readfile, meta }: TransformerProps) {
  const content = await readfile?.();

  return parseMarkdown(content ?? "", meta.flag);
}

The code above is a boilerplate/react/files/$README.md.ts file, which is a file as part of the feature flag react. If theoretical props.meta.flag would provide react, I would add this as a second parameter to the function parseMarkdown which creates the instance of the markdown class. packages/core/src/loaders.ts:

export async function loadMarkdown({ readfile, meta }: TransformerProps) {
  const content = await readfile?.();

  return parseMarkdown(content ?? "", meta.flag);
}

Okay, would there be a limitation to write it like this then?

export async function loadMarkdown({ readfile, meta }: TransformerProps) {
  const content = await readfile?.();

  return parseMarkdown(content ?? "", "react");
}

To simplify the discussion 😄 :

1. adapted meta to include a localContext in packages/build/src/index.ts
2. configure the markdown class with loadMarkdown in packages/core/src/loaders.ts
3. add a second function addMarkdownFeature to make it clear that this will add content to the feature section
4. add a table of content - place can be defined in the first readme boilerplates/shared/files/$TEST.md.ts

to test run pnpm cli --react --sentry --aws

This is still a draft and needs some cleanup but should be feature complete.

The only known bugs are headers with special characters which are not correctly converted to internal links e.g.

### `/pages/+config.ts\`

My remarks about not being able to extract the current flag from the boilerplate name still stands. Its wrong to assume the boilerplate folder name is the flag, it's usually a coincidence for readability, but you cannot assume that this is or will always be the case.

This means that localContext as no conceptual meaning with the current achitecture of Bati.
It should be removed, and with a slight modification, addMarkdownFeature can take an explicit flag as I suggested:

addMarkdownFeature(markdown: string | ZoneHandler, flag: Flags) {
  const category = features.find((f) => f.flag === flag)!.category as CategoryLabels;
  this.contents.push({ markdown, options: { wrapper: { category, flag } } });
}

// usage becomes

content.addMarkdownFeature(todo, "aws");

My remarks about not being able to extract the current flag from the boilerplate name still stands. Its wrong to assume the boilerplate folder name is the flag, it's usually a coincidence for readability, but you cannot assume that this is or will always be the case.

This means that localContext as no conceptual meaning with the current achitecture of Bati. It should be removed, and with a slight modification, addMarkdownFeature can take an explicit flag as I suggested:

addMarkdownFeature(markdown: string | ZoneHandler, flag: Flags) {
  const category = features.find((f) => f.flag === flag)!.category as CategoryLabels;
  this.contents.push({ markdown, options: { wrapper: { category, flag } } });
}

// usage becomes

content.addMarkdownFeature(todo, "aws");

I agree, that reengineering from the path is not the best way, but was a fast solution to show what I need. The right way would be to provide this information with the sources list, but this will be a bigger change in the build source code.

To finish this, I will implement it as suggest by you and wait for the next use case to convince you that the name of the boilerplate value needed in transformed templates ;-)

@magne4000 removed localContext and implemented as suggested by you.

Have a last check with this sample boilerplates:
pnpm cli --react --aws --hono --sentry
There should be a TEST.md in the created project.

If there is nothing else to change, I would convert all existing README.md files to the new format.

I have implemented a more robust approach to edit package.json files. New transformers (like the one you are writing for this PR) can now implement StringTransformer.
If you return an object that implements StringTransformer function in any $....ts file, it will automatically call its finalize() method upon build.

👏 Thank you very much!